/* -*-             c-basic-offset: 4; indent-tabs-mode: nil; -*-  //------100-columns-wide------>|*/
// for license please see accompanying LICENSE.txt file (available also at http://www.xmlpull.org/)

package org.xmlpull.v1;

import java.io.InputStream;
import java.io.IOException;
import java.io.Reader;

/**
 * XML Pull Parser (分析器)is an interface that defines parsing functionality provided in <a href="http://www.xmlpull.org/">XMLPULL V1 API</a>
 * XML Pull Parser是定义 XMLPULL V1 API 中提供的解析功能的接口
 * (visit this website to learn more about API and its implementations).
 *请访问此网站以了解更多关于API及其实施的信息
 * <p>There are following different kinds of parser depending on which features are set:<ul>
 *     有以下不同类型的分析器，具体取决于哪些功能设置
 * <li><b>non-validating（非验证）</b>
 * parser as defined in XML 1.0 spec
 * 解析器在XML 1.0规范中定义
 * when  FEATURE_PROCESS_DOCDECL is set to true <li><b>validating parser</b> as defined in XML 1.0 spec
 * feature(特征) process（处理） docdecl
 *当将FEATURE PROCESS DOCDECL设置为true时，XML 1.0规范中定义的验证解析器
 * when FEATURE_VALIDATION is true (and that implies that FEATURE_PROCESS_DOCDECL is true)
 * 当功能确认为真（这意味着功能处理DOCDECL为真）
 * <li>when FEATURE_PROCESS_DOCDECL is false (this is default and if different value is required necessary must be changed before parsing is started)
 * 当FEATURE PROCESS DOCDECL为false时（这是默认的，如果需要不同的值，必须在解析开始前改变）
 *   then parser behaves like XML 1.0 compliant non-validating parser under condition that <em>no DOCDECL is present</em> in XML documents
 *   那么在XML文档中 不存在 o DOCDECL的情况下，解析器的行为就像XML 1.0兼容的非验证解析器
 *   (internal entites can still be defined with defineEntityReplacementText()).
 *   （内部实体仍然可以通过定义实体替换文本（）来定义）。
 *   This mode of operation is intended <b>for operation in constrained environments</b> such as J2ME.
 *   种操作模式旨在用于在约束环境下操作，如J2 ME
 * </ul>
 *
 *
 * <p>There are two key methods: next() and nextToken().
 * While next() provides access to high level parsing events, nextToken() allows access to lower level tokens.
 *当next（）提供对高级解析事件的访问时，下一个Token（）允许访问较低级别的标记。
 * <p>The current event state of the parser can be determined by calling the
 * 解析器的当前事件状态可以通过调用
 * <a href="#getEventType()">getEventType()</a> method.
 * Initially, the parser is in the <a href="#START_DOCUMENT">START_DOCUMENT</a> state.
 *最初，解析器处于 START DOCUMENT 状态
 * <p>The method <a href="#next()">next()</a> advances the parser to the next event.
 *方法 next（）将解析器推进到下一个事件。
 * The int value returned from next determines the current parser state and is identical to the value returned from following calls to getEventType ().
 *从next返回的int值决定了当前的分析器状态，并且与以下调用返回的值相同以获得Event Type（）
 * <p>Th following event types are seen by next()<dl>
 *     以下事件类型可见（）
 * <dt><a href="#START_TAG">START_TAG</a><dd> An XML start tag was read.
 * <dt><a href="#TEXT">TEXT</a><dd> Text content was read;
 * the text content can be retrieved using the getText() method.
 * 文本内容可以使用get（）方法获取
 *  (when in validating mode next() will not report ignorable whitespace, use nextToken() instead)
 *  （在验证模式next（）不会报告可忽略的空白时，使用下一个Token（）来代替）
 * <dt><a href="#END_TAG">END_TAG</a><dd> An end tag was read
 * <dt><a href="#END_DOCUMENT">END_DOCUMENT</a><dd> No more events are available（可得到）
 * </dl>
 *
 * <p>after first next() or nextToken() (or any other next*() method) is called user application can obtain XML version,
 * 在第一个下一个（）或下一个Token（）（或任何其他next（）方法）之后被调用的用户应用程序可以获得XML版本
 * standalone and encoding from XML declaration in following ways:
 * 以下面的方式独立于XML声明并进行编码<ul>
 * <li><b>version</b>:
 *  getProperty(&quot;<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">http://xmlpull.org/v1/doc/properties.html#xmldecl-version</a>&quot;)
 *       returns String ("1.0") or null if XMLDecl was not read or if property is not supported
 * <li><b>standalone（独立）</b>:
 *  getProperty(&quot;<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone">http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone</a>&quot;)
 *       returns Boolean:
 *       null if there was no standalone declaration or if property is not supported
 *       如果没有独立声明或者不支持属性，则返回null
 *         otherwise returns Boolean(true) if standalone="yes" and Boolean(false)
 *         否则如果standalone =“yes”和Boolean（false）返回布尔值（true）
 *         when standalone="no"
 *
 *         <li><b>encoding</b>:
 *         obtained from getInputEncoding() null if stream had unknown encoding (not set in setInputStream) and it was not declared in XMLDecl
 * </ul>
 *
 * A minimal（最小） example for using this API may look as follows:
 * <pre>
 * import java.io.IOException;
 * import java.io.StringReader;
 *
 * import org.xmlpull.v1.XmlPullParser;
 * import org.xmlpull.v1.<a href="XmlPullParserException.html">XmlPullParserException</a>;
 * import org.xmlpull.v1.<a href="XmlPullParserFactory.html">XmlPullParserFactory</a>;
 *
 * public class SimpleXmlPullApp
 * {
 *
 *     public static void main (String args[])
 *         throws XmlPullParserException, IOException
 *     {
 *         XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
 *         factory.setNamespaceAware(true);
 *         XmlPullParser xpp = factory.newPullParser();
 *
 *         xpp.<a href="#setInput">setInput</a>( new StringReader ( "&lt;foo>Hello World!&lt;/foo>" ) );
 *         int eventType = xpp.getEventType();
 *         while (eventType != XmlPullParser.END_DOCUMENT) {
 *          if(eventType == XmlPullParser.START_DOCUMENT) {
 *              System.out.println("Start document");
 *          } else if(eventType == XmlPullParser.START_TAG) {
 *              System.out.println("Start tag "+xpp.<a href="#getName()">getName()</a>);
 *          } else if(eventType == XmlPullParser.END_TAG) {
 *              System.out.println("End tag "+xpp.getName());
 *          } else if(eventType == XmlPullParser.TEXT) {
 *              System.out.println("Text "+xpp.<a href="#getText()">getText()</a>);
 *          }
 *          eventType = xpp.next();
 *         }
 *         System.out.println("End document");
 *     }
 * }
 * </pre>
 *
 * <p>The above example will generate the following output:
 * <pre>
 * Start document
 * Start tag foo
 * Text Hello World!
 * End tag foo
 * End document
 * </pre>
 *
 * <p>For more details on API usage, please refer to the
 * quick Introduction available at <a href="http://www.xmlpull.org">http://www.xmlpull.org</a>
 *
 * @see XmlPullParserFactory
 * @see #defineEntityReplacementText
 * @see #getName
 * @see #getNamespace
 * @see #getText
 * @see #next
 * @see #nextToken
 * @see #setInput
 * @see #FEATURE_PROCESS_DOCDECL
 * @see #FEATURE_VALIDATION
 * @see #START_DOCUMENT
 * @see #START_TAG
 * @see #TEXT
 * @see #END_TAG
 * @see #END_DOCUMENT
 *
 * @author <a href="http://www-ai.cs.uni-dortmund.de/PERSONAL/haustein.html">Stefan Haustein</a>
 * @author <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
 */

public interface XmlPullParser {

    /** This constant represents the default namespace (empty string "")
     * 这个常量表示默认的命名空间
     * */
    String NO_NAMESPACE = "";

    // ----------------------------------------------------------------------------
    // EVENT TYPES as reported by next()

    /**
     * Signalize that parser is at the very beginning of the document and nothing was read yet.
     * 指出解析器在文档的开头，没有任何东西被读取。
     * This event type can only be observed by calling getEvent() before the first call to next(), nextToken, or nextTag()
     * 这个事件类型只有在第一次调用next（），next Token或next Tag（）之前调用get（）
     * </a>).
     *
     * @see #next
     * @see #nextToken
     */
    int START_DOCUMENT = 0;

    /**
     * Logical end of the xml document. Returned from getEventType, next() and nextToken() when the end of the input document has been reached.
     * 从输入文档的末尾到达时，返回Event Type，next（）和Next Token（）。
     * <p><strong>NOTE:</strong> subsequent calls to <a href="#next()">next()</a> or <a href="#nextToken()">nextToken()</a> may result in exception being thrown.
     *后续调用 next 或下一个Token（） 可能会导致抛出异常
     * @see #next
     * @see #nextToken
     */
    int END_DOCUMENT = 1;

    /**
     * Returned from getEventType(),
     * <a href="#next()">next()</a>, <a href="#nextToken()">nextToken()</a> when
     * a start tag was read.
     * The name of start tag is available（可获得） from getName(), its namespace and prefix(前缀) are
     * available from getNamespace() and getPrefix()
     * if <a href='#FEATURE_PROCESS_NAMESPACES'>namespaces are enabled</a>.
     * See getAttribute* methods to retrieve element attributes.
     * 请参阅get属性方法来检索元素属性
     * See getNamespace* methods to retrieve newly declared namespaces.
     * 请参阅获取名称空间方法来检索新声明的名称空间。
     *
     * @see #next
     * @see #nextToken
     * @see #getName
     * @see #getPrefix
     * @see #getNamespace
     * @see #getAttributeCount
     * @see #getDepth
     * @see #getNamespaceCount
     * @see #getNamespace
     * @see #FEATURE_PROCESS_NAMESPACES
     */
    int START_TAG = 2;

    /**
     * Returned from getEventType(), <a href="#next()">next()</a>, or
     * <a href="#nextToken()">nextToken()</a> when an end tag was read.
     * The name of start tag is available from getName(), its
     * namespace and prefix are
     * available from getNamespace() and getPrefix().
     *
     * @see #next
     * @see #nextToken
     * @see #getName
     * @see #getPrefix
     * @see #getNamespace
     * @see #FEATURE_PROCESS_NAMESPACES
     */
    int END_TAG = 3;


    /**
     * Character data was read and will is available by calling getText().
     * <p><strong>Please note:</strong> <a href="#next()">next()</a> will accumulate multiple events into one TEXT event,
     * 将多个事件累加到一个TEXT事件中
     * skipping IGNORABLE_WHITESPACE,PROCESSING_INSTRUCTION and COMMENT events,
     * 跳过IGNORABLE WHITESPACE，处理指导和评论事件
     * In contrast, <a href="#nextToken()">nextToken()</a> will stop reading text when any other event is observed.
     * 相反，当观察到其他事件时， next Token（）将停止阅读文本。
     * Also, when the state was reached by calling next(), the text value will be normalized,
     * 而且，当通过调用next（）来达到状态时，文本值将被标准化
     * whereas getText() will return unnormalized content in the case of nextToken().
     * ：而在下一个Token（）的情况下，获取Text（）将返回非标准化的内容。
     * This allows an exact roundtrip without changing line ends when examining low level events,
     * whereas for high level applications the text is normalized appropriately.
     *当检查低级事件时，这允许精确的往返而不改变行结束，而对于高级应用程序，文本被适当地标准化。
     * @see #next
     * @see #nextToken
     * @see #getText
     */
    int TEXT = 4;

    // ----------------------------------------------------------------------------
    // additional events exposed by lower level nextToken()
    //下一级显示的附加事件Token（）

    /**
     *
     * 一个CDATA部分刚刚阅读;
     * this token is available only from calls to <a href="#nextToken()">nextToken()</a>.
     * 这个令牌只能通过调用下一个Token（）
     * A call to next() will accumulate various text events into a single event of type TEXT.
     * 对next（）的调用会将各种文本事件累加到TEXT类型的单个事件中。
     * The text contained in the CDATA section is available by calling getText().
     *含在CDATA部分中的文本可以通过调用get Text（）来获得
     * @see #nextToken
     * @see #getText
     */
    int CDSECT = 5;

    /**
     * An entity reference was just read;
     * 一个实体引用刚刚被读取;
     * this token is available from <a href="#nextToken()">nextToken()</a> only.
     * 此令牌仅可从下nextToken()获得
     * The entity name is available by calling getName().
     * 实体名称可通过调用get Name（）来获得。
     * If available, the replacement text can be obtained by calling getText(); otherwise,
     * 如果可用，则可以通过调用get Text（）来获得替换文本。 除此以外，
     * the user is responsible for resolving the entity reference.
     * 用户负责解决实体引用
     * This event type is never returned from next(); next() will accumulate the replacement text and other text events to a single TEXT event.
     *这个事件类型永远不会从next（）返回。 next（）会将替换文本和其他文本事件累加到一个TEXT事件中。
     * @see #nextToken
     * @see #getText
     */
    int ENTITY_REF = 6;

    /**
     * Ignorable whitespace was just read.
     * 可读的空白字符刚刚被读取
     * This token is available only from <a href="#nextToken()">nextToken()</a>).
     * 该令牌只能从nextToken获得。
     * For non-validating parsers, this event is only reported by nextToken() when outside the root element.
     * 对于非验证解析器，只有在根元素之外的情况下才会通过下一个Token（）报告此事件。
     * Validating parsers may be able to detect ignorable whitespace at other locations.
     * 验证解析器可能能够在其他位置检测到可忽略的空白
     * The ignorable whitespace string is available by calling getText()
     *可忽略的空白字符串可通过调用get Text（）
     * <p><strong>NOTE:</strong>
     * this is different from calling the isWhitespace() method, since text content may be whitespace but not ignorable.
     *这与调用Whitespace（）方法不同，因为文本内容可能是空格而不是可以忽略的
     * Ignorable whitespace is skipped by next() automatically; this event type is never returned from next().
     *：next（）会自动跳过可忽略的空格; 这个事件类型永远不会从next（）返回
     * @see #nextToken
     * @see #getText
     */
    int IGNORABLE_WHITESPACE = 7;

    /**
     * An XML processing instruction declaration was just read.
     * ：刚刚阅读了XML处理指令声明
     * This event type is available only via <a href="#nextToken()">nextToken()</a>.
     * 此事件类型只能通过nextToken（）获得
     * getText() will return text that is inside the processing instruction.
     * getText() 将返回处理指令中的文本。
     * Calls to next() will skip processing instructions automatically.
     * 调用next（）会自动跳过处理指令
     * @see #nextToken
     * @see #getText
     * processing(处理) instruction（指令）:
     */
    int PROCESSING_INSTRUCTION = 8;

    /**
     * An XML comment was just read. This event type is this token is
     * available via <a href="#nextToken()">nextToken()</a> only;
     * calls to next() will skip comments automatically.
     * The content of the comment can be accessed using the getText()
     * method.
     *
     * @see #nextToken
     * @see #getText
     */
    int COMMENT = 9;

    /**
     * An XML document type declaration was just read.
     * 刚刚阅读了XML文档类型声明
     * This token is available from <a href="#nextToken()">nextToken()</a> only.
     * The unparsed text inside the doctype is available via the getText() method.
     *octype中的未解析文本可以通过get Text（）方法获得。
     * @see #nextToken
     * @see #getText
     */
    int DOCDECL = 10;

    /**
     * This array can be used to convert the event type integer constants such as START_TAG or TEXT to to a string.
     * ：这个数组可以用来将事件类型的整型常量（如START TAG或TEXT）转换为字符串
     * For example, the value of TYPES[START_TAG] is
     * the string "START_TAG".
     *
     * This array is intended for diagnostic output only.
     * 该阵列仅用于诊断输出
     * Relying on the contents of the array may be dangerous since malicious applications may alter the array, although it is final, due to limitations of the Java language.
     * 依赖于数组的内容可能是危险的，因为恶意应用程序可能会改变数组，尽管这是最终的，由于Java语言的限制。
     */
    String [] TYPES = {
        "START_DOCUMENT",
            "END_DOCUMENT",
            "START_TAG",
            "END_TAG",
            "TEXT",
            "CDSECT",
            "ENTITY_REF",
            "IGNORABLE_WHITESPACE",
            "PROCESSING_INSTRUCTION",
            "COMMENT",
            "DOCDECL"
    };


    // ----------------------------------------------------------------------------
    // namespace related features
    //名空间相关的功能

    /**
     * This feature determines whether the parser processes namespaces. As for all features, the default value is false.
     * 此功能确定解析器是否处理名称空间。 至于所有功能，默认值是false。
     * <p><strong>NOTE:</strong>
     * The value can not be changed during parsing an must be set before parsing.
     *在分析过程中，值不能被改变
     * @see #getFeature
     * @see #setFeature
     * feature process namespaces
     */
    String FEATURE_PROCESS_NAMESPACES =
        "http://xmlpull.org/v1/doc/features.html#process-namespaces";

    /**
     * This feature determines whether namespace attributes are exposed via the attribute access methods.
     * 此功能确定是否通过属性访问方法公开名称空间属性。
     * Like all features, the default value is false. This feature cannot be changed during parsing.
     *像所有功能一样，默认值为false。 该功能在解析过程中无法更改。
     * @see #getFeature
     * @see #setFeature
     * feature report namespace attributes
     */
    String FEATURE_REPORT_NAMESPACE_ATTRIBUTES =
        "http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes";

    /**
     * This feature determines whether the document declaration is processed.
     * 此功能确定是否处理文档声明
     * If set to false,the DOCDECL event type is reported by nextToken() and ignored by next().
     *如果设置为false，则DOCDECL事件类型由下一个Token（）报告，并由next（）忽略。
     * If this feature is activated, then the document declaration must be processed by the parser.
     *如果此功能被激活，则文档声明必须由解析器处理
     * <p><strong>Please note:</strong>
     * If the document type declaration was ignored, entity references may cause exceptions later in the parsing process.
     * 如果文档类型声明被忽略，则实体引用可能会在解析过程中稍后导致异常
     * The default value of this feature is false. It cannot be changed during parsing.
     *此功能的默认值为false。 在解析过程中不能更改。
     * @see #getFeature
     * @see #setFeature
     * feature process docdecl
     */
    String FEATURE_PROCESS_DOCDECL =
        "http://xmlpull.org/v1/doc/features.html#process-docdecl";

    /**
     * If this feature is activated, all validation errors as defined in the XML 1.0 specification are reported.
     * ：如果激活此功能，则会报告XML 1.0规范中定义的所有验证错误。
     * This implies that FEATURE_PROCESS_DOCDECL is true and both, the internal and external document type declaration will be processed.
     * 这意味着功能过程DOCDECL是正确的，并且内部和外部文档类型声明都将被处理。
     * <p><strong>Please Note:</strong> This feature can not be changed during parsing. The default value is false.
     * 该功能在解析过程中无法更改。 默认值是false。
     *
     * @see #getFeature
     * @see #setFeature
     * feature validation
     */
    String FEATURE_VALIDATION =
        "http://xmlpull.org/v1/doc/features.html#validation";

    /**
     * Use this call to change the general behaviour of the parser,
     * 使用这个调用来改变解析器的一般行为
     * such as namespace processing or doctype declaration handling.
     * 如命名空间处理或doctype声明处理。
     * This method must be called before the first call to next or nextToken.
     * Otherwise, an exception is thrown.
     * <p>Example: call setFeature(FEATURE_PROCESS_NAMESPACES, true) in order
     * to switch on namespace processing.
     * The initial settings correspond to the properties requested from the XML Pull Parser factory.
     * 初始设置对应于XML Pull Parser工厂请求的属性
     * If none were requested, all features are deactivated by default.
     *如果没有请求，则默认情况下将禁用所有功能
     * @exception XmlPullParserException If the feature is not supported or can not be set
     * @exception IllegalArgumentException If string with the feature name is null
     */
    void setFeature(String name,
                           boolean state) throws XmlPullParserException;

    /**
     * Returns the current value of the given feature.
     * 返回给定特征的当前值
     * <p><strong>Please note:</strong> unknown features are
     * <strong>always</strong> returned as false.
     *
     * @param name The name of feature to be retrieved.
     * @return The value of the feature.
     * @exception IllegalArgumentException if string the feature name is null
     */

    boolean getFeature(String name);

    /**
     * Set the value of a property.
     *设置一个属性的值
     * The property name is any fully-qualified URI.
     *属性名称是任何完全限定的URI
     * @exception XmlPullParserException If the property is not supported or can not be set
     * @exception IllegalArgumentException If string with the property name is null
     */
    void setProperty(String name,
                            Object value) throws XmlPullParserException;

    /**
     * Look up the value of a property.
     *
     * The property name is any fully-qualified URI.
     * <p><strong>NOTE:</strong> unknown properties are <strong>always</strong>
     * returned as null.
     *
     * @param name The name of property to be retrieved.
     * @return The value of named property.
     */
    Object getProperty(String name);


    /**
     * Set the input source for parser to the given reader and resets the parser.
     * 将解析器的输入源设置为给定的阅读器，并重置解析器
     * The event type is set to the initial value START_DOCUMENT.
     * 事件类型被设置为初始值START DOCUMENT。
     * Setting the reader to null will just stop parsing and reset parser state,
     * 将reader设置为null将停止解析并重置解析器状态，
     * allowing the parser to free internal resources such as parsing buffers.
     * 允许解析器释放内部资源，如解析缓冲区。
     */
    void setInput(Reader in) throws XmlPullParserException;


    /**
     * Sets the input stream the parser is going to process.
     * 设置解析器将要处理的输入流
     * This call resets the parser state and sets the event type to the initial value START_DOCUMENT.
     *该调用重置解析器状态并将事件类型设置为初始值START DOCUMENT。
     * <p><strong>NOTE:</strong>
     * If an input encoding string is passed,it MUST be used. Otherwise,
     * 如果输入的编码字符串被传递，它必须被使用。 除此以外，
     *  if inputEncoding is null, the parser SHOULD try to determine input encoding following XML 1.0 specification (see below).
     *  ：如果输入编码为空，则解析器应该尝试确定遵循XML 1.0规范的输入编码（见下文）。
     *  If encoding detection is supported then following feature
     *  如果支持编码检测，则使用以下功能
     *  <a href="http://xmlpull.org/v1/doc/features.html#detect-encoding">http://xmlpull.org/v1/doc/features.html#detect-encoding</a>
     *  MUST be true amd otherwise it must be false
     *  必须是真的，否则它一定是假的
     *
     * @param inputStream contains a raw byte input stream of possibly
     *     unknown encoding (when inputEncoding is null).
     *
     * @param inputEncoding if not null it MUST be used as encoding for inputStream
     */
    void setInput(InputStream inputStream, String inputEncoding)
        throws XmlPullParserException;

    /**
     * Returns the input encoding if known, null otherwise.
     * 返回输入编码（如果已知），否则返回null。
     * If setInput(InputStream, inputEncoding) was called with an inputEncoding value other than null, this value must be returned from this method.
     * 如果设置输入（输入流，输入编码）被调用输入编码值非空，该值必须从此方法返回。
     * Otherwise, if inputEncoding is null and the parser supports the encoding detection feature
     * 否则，如果输入编码为空，解析器支持编码检测功能
     * (http://xmlpull.org/v1/doc/features.html#detect-encoding),
     * it must return the detected encoding.
     * 它必须返回检测到的编码。
     * If setInput(Reader) was called, null is returned.
     * 如果设置Input（Reader）被调用，则返回null。
     * After first call to next if XML declaration was present this method will return encoding declared.
     * 在第一次调用next时，如果存在XML声明，则此方法将返回声明的编码。
     */
    String getInputEncoding();

    /**
     * Set new value for entity replacement text as defined in
     * 据定义，为实体替换文本设置新的值
     * <a href="http://www.w3.org/TR/REC-xml#intern-replacement">XML 1.0 Section 4.5
     * Construction of Internal Entity Replacement Text
     * 内部实体替代文本的构建</a>.
     * If FEATURE_PROCESS_DOCDECL or FEATURE_VALIDATION are set,
     * 如果FEATURE PROCESS DOCDECL或FEATURE VALIDATION已设置
     * calling this function will result in an exception -- when processing of DOCDECL is enabled, there is no need to the entity replacement text manually.
     *调用此函数将导致异常 - 启用DOCDECL处理时，不需要手动更换实体文本。
     * <p>The motivation for this function is to allow very small implementations of XMLPULL that will work in J2ME environments.
     * 这个功能的动机是允许在J2ME环境中工作的XMLPULL的非常小的实现
     * Though these implementations may not be able to process the document type declaration, they still can work with known DTDs by using this function.
     *虽然这些实现可能无法处理文档类型声明，但它们仍然可以使用此函数使用已知的DTD
     * <p><b>Please notes:</b>
     *
     * The given value is used literally as replacement text and it corresponds to declaring entity in DTD that has all special characters escaped:
     * 给定的值被直接用作替换文本，它对应于在DTD中声明所有特殊字符转义的实体
     * left angle bracket is replaced with &amp;lt;, ampersand with &amp;amp; and so on.
     *左角括号替换为＆amp; lt，＆amp; amp; amp; amp; 等等。
     * <p><b>Note:</b>
     * The given value is the literal replacement text and must not contain any other entity reference (if it contains any entity reference there will be no further replacement).
     *给定的值是字面替换文本，不得包含任何其他实体引用（如果它包含任何实体引用，则不会有进一步的替换）
     * <p><b>Note:</b>
     * The list of pre-defined entity names will always contain standard XML entities such as amp (&amp;amp;), lt (&amp;lt;), gt (&amp;gt;), quot (&amp;quot;), and apos (&amp;apos;).
     * 预定义实体名称的列表将总是包含诸如amp（＆amp; amp; amp;），lt（＆amp; lt;），gt（＆amp; gt;），quot（＆amp; quot;）的标准XML实体， （安培;'）上。
     * Those cannot be redefined by this method!
     * 那些不能用这个方法重新定义
     *
     * @see #setInput
     * @see #FEATURE_PROCESS_DOCDECL
     * @see #FEATURE_VALIDATION
     */
    void defineEntityReplacementText( String entityName,
                                            String replacementText ) throws XmlPullParserException;

    /**
     * Returns the numbers of elements in the namespace stack for the given depth.
     * 返回给定深度的命名空间堆栈中元素的数量
     * If namespaces are not enabled, 0 is returned.
     *如果命名空间未启用，则返回0
     * <p><b>NOTE:</b>
     * when parser is on END_TAG then it is allowed to call this function with getDepth()+1 argument to retrieve position of namespace prefixes
     * ：当解析器在END TAG上时，允许使用get Depth（）+ 1参数调用该函数来检索名称空间前缀的位置
     * and URIs that were declared on corresponding START_TAG.
     * 以及在相应的START标签上声明的URI。
     * <p><b>NOTE:</b> t
     * o retrieve list of namespaces declared in current element:
     * 检索在当前元素中声明的名称空间列表：<pre>
     *       XmlPullParser pp = ...
     *       int nsStart = pp.getNamespaceCount(pp.getDepth()-1);
     *       int nsEnd = pp.getNamespaceCount(pp.getDepth());
     *       for (int i = nsStart; i < nsEnd; i++) {
     *          String prefix = pp.getNamespacePrefix(i);
     *          String ns = pp.getNamespaceUri(i);
     *           // ...
     *      }
     * </pre>
     *
     * @see #getNamespacePrefix
     * @see #getNamespaceUri
     * @see #getNamespace()
     * @see #getNamespace(String)
     */
    int getNamespaceCount(int depth) throws XmlPullParserException;

    /**
     * Returns the namespace prefix for the given position in the namespace stack.
     * 返回命名空间堆栈中给定位置的名称空间前缀。
     * Default namespace declaration (xmlns='...') will have null as prefix.
     * 默认名称空间声明（xmlns ='...'）将以空格作为前缀。
     * If the given index is out of range, an exception is thrown.
     * 如果给定的索引超出范围，则抛出异常。
     * <p><b>Please note:</b>
     * when the parser is on an END_TAG,
     * namespace prefixes that were declared  in the corresponding START_TAG are still accessible although they are no longer in scope.
     * 在相应的START TAG中声明的名称空间前缀仍然可以访问，尽管它们不在范围之内
     */
    String getNamespacePrefix(int pos) throws XmlPullParserException;

    /**
     * Returns the namespace URI for the given position in the namespace stack
     * 返回命名空间堆栈中给定位置的名称空间URI
     * If the position is out of range, an exception is thrown.
     * 如果位置超出范围，则抛出异常
     * <p><b>NOTE:</b>
     * when parser is on END_TAG then
     * namespace prefixes that were declared in corresponding START_TAG are still accessible even though they are not in scope
     * 在相应的START TAG中声明的名称空间前缀仍然可以访问，即使它们不在作用域中
     */
    String getNamespaceUri(int pos) throws XmlPullParserException;

    /**
     * Returns the URI corresponding to the given prefix, depending on current state of the parser.
     *根据解析器的当前状态返回与给定前缀对应的URI
     * <p>If the prefix was not declared in the current scope,null is returned.
     * 如果前缀未在当前作用域中声明，则返回null
     * The default namespace is included  in the namespace table and is available via getNamespace (null).
     *默认名称空间包含在名称空间表中，可通过get Namespace（null）使用。
     * <p>This method is a convenience method for
     *这个方法是一个方便的方法
     * <pre>
     *  for (int i = getNamespaceCount(getDepth ())-1; i >= 0; i--) {
     *   if (getNamespacePrefix(i).equals( prefix )) {
     *     return getNamespaceUri(i);
     *   }
     *  }
     *  return null;
     * </pre>
     *
     * <p><strong>Please note:</strong>
     * parser implementations may provide more efficient lookup, e.g. using a Hashtable.
     * 分析器实现可以提供更高效的查找，例如， 使用一个Hashtable。
     * The 'xml' prefix is bound to "http://www.w3.org/XML/1998/namespace", as defined in the
     * “xml”前缀绑定到“http：www.w3.org/ XML / 1998 / namespace”，如上定义
     * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>
     * specification. Analogous, the 'xmlns' prefix is resolved to
     * 规范。 类似的，“xmlns”前缀已经解决了
     * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
     *
     * @see #getNamespaceCount
     * @see #getNamespacePrefix
     * @see #getNamespaceUri
     */
    String getNamespace (String prefix);


    // --------------------------------------------------------------------------
    // miscellaneous reporting methods
    //杂项报告方法

    /**
     * Returns the current depth of the element.
     * 返回元素的当前深度
     * Outside the root element, the depth is 0.
     * 在根元素之外，深度为0
     * The depth is incremented by 1 when a start tag is reached.
     * ：当达到开始标签时，深度加1。
     * The depth is decremented AFTER the end tag event was observed.
     * 在观察结束标记事件后，深度递减
     *
     * <pre>
     * &lt;!-- outside --&gt;     0
     * &lt;root>                  1
     *   sometext                 1
     *     &lt;foobar&gt;         2
     *     &lt;/foobar&gt;        2
     * &lt;/root&gt;              1
     * &lt;!-- outside --&gt;     0
     * </pre>
     */
    int getDepth();

    /**
     * Returns a short text describing the current parser state,
     * 返回描述当前解析器状态的简短文本
     * including the position, a description of the current event and the data source if known.
     * 括位置，当前事件的描述和数据源（如果已知）。
     * This method is especially useful to provide meaningful error messages and for debugging purposes.
     * 此方法对于提供有意义的错误消息和用于调试目的特别有用
     */
    String getPositionDescription ();


    /**
     * Returns the current line number, starting from 1.
     * 返回当前行号，从1开始。
     * When the parser does not know the current line number or can not determine it,  -1 is returned (e.g. for WBXML).
     *当解析器不知道当前行号或无法确定它时，返回-1（例如，用于WBXML）
     * @return current line number or -1 if unknown.
     */
    int getLineNumber();

    /**
     * Returns the current column number, starting from 0.
     * 返回当前列号，从0开始
     * When the parser does not know the current column number
     * or can not determine it,  -1 is returned (e.g. for WBXML).
     *
     * @return current column number or -1 if unknown.
     */
    int getColumnNumber();


    // --------------------------------------------------------------------------
    // TEXT related methods
    //TEXT相关的方法

    /**
     * Checks whether the current TEXT event contains only whitespace characters.
     * 检查当前的TEXT事件是否只包含空格字符
     * For IGNORABLE_WHITESPACE, this is always true.
     * 对于IGNORABLE WHITESPACE，这总是如此
     * For TEXT and CDSECT, false is returned when the current event text contains at least one non-white space character.
     * 对于TEXT和CDSECT，当当前事件文本至少包含一个非空白字符时，返回fals
     * For any other  event type an exception is thrown.
     *对于任何其他事件类型，抛出异常
     *
     * <p><b>Please note:</b>
     * non-validating parsers are not able to distinguish whitespace and ignorable whitespace,
     * 不验证的解析器不能区分空白和可忽略的空白
     * except from whitespace outside the root element.
     * 除了根元素之外的空格之外
     * Ignorable whitespace is reported as separate event, which is exposed via nextToken only.
     *可忽略的空白报告为单独的事件，仅通过下一个令牌暴露
     */
    boolean isWhitespace() throws XmlPullParserException;

    /**
     * Returns the text content of the current event as String.
     * 以String形式返回当前事件的文本内容
     * The value returned depends on current event type,
     * 返回的值取决于当前的事件类型
     * for example for TEXT event it is element content (this is typical case when next() is used).
     *：例如对于TEXT事件，它是元素内容（这是使用next（）时的典型情况）
     * See description of nextToken() for detailed description of possible returned values for different types of events.
     *有关不同类型事件的可能返回值的详细描述，请参阅下一个Token（）的描述
     * <p><strong>NOTE:</strong>
     * in case of ENTITY_REF, this method returns the entity replacement text (or null if not available).
     * 如果是ENTITY REF，则此方法将返回实体替换文本（如果不可用，则返回null）
     * This is  the only case where  getText() and getTextCharacters() return different values.
     *这是得到Text（）和获取文本字符（）返回不同值的唯一情况。
     * @see #getEventType
     * @see #next
     * @see #nextToken
     */
    String getText ();


    /**
     * Returns the buffer that contains the text of the current event,
     * 返回包含当前事件文本的缓冲区
     * as well as the start offset and length relevant for the current event. See getText(), next() and nextToken() for description of possible returned values.
     *以及与当前事件相关的起始偏移量和长度。 有关可能的返回值的描述，请参阅获取Text（），next（）和下一个Token（）
     *
     * <p><strong>Please note:</strong>
     * this buffer must not be modified and its content MAY change after a call to next() or nextToken().
     * 在调用next（）或下一个Token（）之后，这个缓冲区不能被修改，并且它的内容可能会改变
     * This method will always return the same value as getText(), except for ENTITY_REF.
     *这个方法总是返回相同的值作为getText(),除了ENTITY_REF。
     * In the case of ENTITY ref, getText() returns the replacement text and
     * 在实体裁判的情况下,()返回替换文本和文本;
     * this method returns the actual input buffer containing the entity name.
     * 该方法返回包含实体名称的实际输入缓冲区。
     * If getText() returns null, this method returns null as well and the values returned in the holder array MUST be -1 (both start and length).
     *如果getText()返回null,这个方法返回null,持有人数组中返回的值必须是1(开始和长度)。
     * @see #getText
     * @see #next
     * @see #nextToken
     *
     * @param holderForStartAndLength Must hold an 2-element int array into which the start offset and length values will be written.
     *                                必须持有2-element int数组的起始偏移量和长度值将会写。
     * @return char buffer that contains the text of the current event (null if the current event has no text associated).
     * 包含文本字符缓冲区的当前事件(null如果当前事件没有关联文本)。
     */
    char[] getTextCharacters(int [] holderForStartAndLength);

    // --------------------------------------------------------------------------
    // START_TAG / END_TAG shared methods
    //开始标记和结束标记共享方法

    /**
     * Returns the namespace URI of the current element.
     * 返回当前元素的名称空间URI
     * The default namespace is represented as empty string.
     * 默认名称空间表示为空字符串。
     * If namespaces are not enabled, an empty String ("") is always returned.
     * 如果未启用名称空间,总是返回空字符串(" ")。
     * The current event must be START_TAG or END_TAG; otherwise, null is returned.
     * 当前事件必须看到START_TAG或END_TAG;否则,将返回空值。
     */
    String getNamespace ();

    /**
     * For START_TAG or END_TAG events, the (local) name of the current element is returned when namespaces are enabled.
     * 开始标记和结束标记事件,当前元素的(当地)名称返回当启用名称空间。;
     * When namespace processing is disabled, the raw name is returned.
     * 当名称空间处理是禁用的,返回的原始名称。
     * For ENTITY_REF events, the entity name is returned.
     * 返回ENTITY_REF事件,实体名称。
     * If the current event is not START_TAG, END_TAG, or ENTITY_REF, null is returned.
     * 如果当前事件不是开始标记、结束标记,或实体裁判,返回null。
     * <p><b>Please note:</b> To reconstruct the raw element name
     * 如果当前事件不是开始标记、结束标记,或实体裁判,返回null。
     *  when namespaces are enabled and the prefix is not null, you will need to  add the prefix and a colon to localName..
     *当启用名称空间和前缀不是null,您需要添加前缀和冒号本地名称。;
     */
    String getName();

    /**
     * Returns the prefix of the current element.
     * If the element is in the default namespace (has no prefix),
     * null is returned.
     * If namespaces are not enabled, or the current event
     * is not  START_TAG or END_TAG, null is returned.
     */
    String getPrefix();

    /**
     * Returns true if the current event is START_TAG and the tag
     * is degenerated
     * (e.g. &lt;foobar/&gt;).
     * <p><b>NOTE:</b> if the parser is not on START_TAG, an exception
     * will be thrown.
     */
    boolean isEmptyElementTag() throws XmlPullParserException;

    // --------------------------------------------------------------------------
    // START_TAG Attributes retrieval methods
    //开始标记属性检索方法

    /**
     * Returns the number of attributes of the current start tag, or -1 if the current event type is not START_TAG
     *返回当前的开始标记的属性的数量,或1如果当前事件类型不是开始标记;
     * @see #getAttributeNamespace
     * @see #getAttributeName
     * @see #getAttributePrefix
     * @see #getAttributeValue
     */
    int getAttributeCount();

    /**
     * Returns the namespace URI of the attribute with the given index (starts from 0).
     * 返回与给定的名称空间URI属性指数(从0开始)。
     * Returns an empty string ("") if namespaces are not enabled or the attribute has no namespace.
     * 返回空字符串(" ")如果不启用或名称空间的属性就没有名称空间。
     * Throws an IndexOutOfBoundsException if the index is out of range or the current event type is not START_TAG.
     *抛出一个索引越界异常如果指数范围或当前事件类型不是开始标记;
     * <p><strong>NOTE:</strong> if FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set then namespace attributes (xmlns:ns='...') must be reported with namespace
     * 如果特性报告命名空间属性设置名称空间属性(xmlns:ns =“…”)必须报告名称空间;
     * <a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
     * (visit this URL for description!).
     * (访问这个URL获取描述
     * The default namespace attribute (xmlns="...") will be reported with empty namespace.
     * 默认名称空间属性(xmlns = "…")将公布空名称空间
     * <p><strong>NOTE:</strong>The xml prefix is bound as defined in
     * 中定义的xml前缀被绑定
     * <a href="http://www.w3.org/TR/REC-xml-names/#ns-using">Namespaces in XML</a>
     * specification（规范） to "http://www.w3.org/XML/1998/namespace".
     *
     * @param index zero-based index of attribute从零开始的索引属性
     * @return attribute namespace, 属性名称空间,;
     *   empty string ("") is returned  if namespaces processing is not enabled or namespaces processing is enabled but attribute has no namespace (it has no prefix).
     *   返回空字符串(" ")如果没有启用名称空间处理或名称空间处理但属性没有启用名称空间(它没有前缀)。;
     */
    String getAttributeNamespace (int index);

    /**
     * Returns the local name of the specified attribute if namespaces are enabled or just attribute name if namespaces are disabled.
     * 返回指定的属性的本地名称如果启用名称空间或属性名称名称空间是禁用的。
     * Throws an IndexOutOfBoundsException if the index is out of range
     * or current event type is not START_TAG.
     *
     * @param index zero-based index of attribute
     * @return attribute name (null is never returned)
     */
    String getAttributeName (int index);

    /**
     * Returns the prefix of the specified attribute
     * 返回指定的前缀属性
     * Returns null if the element has no prefix.
     * 如果没有前缀的元素返回null。
     * If namespaces are disabled it will always return null.
     * 如果名称空间被禁用它总是返回null。
     * Throws an IndexOutOfBoundsException if the index is out of range
     * or current event type is not START_TAG.
     *
     * @param index zero-based index of attribute
     * @return attribute prefix or null if namespaces processing is not enabled.
     */
    String getAttributePrefix(int index);

    /**
     * Returns the type of the specified attribute
     * 返回指定的属性的类型
     * If parser is non-validating it MUST return CDATA.
     *
     * @param index zero-based index of attribute
     * @return attribute type (null is never returned)
     */
    String getAttributeType(int index);

    /**
     * Returns if the specified attribute was not in input was declared in XML.
     * 返回如果指定的属性并不是在输入中声明的XML
     * If parser is non-validating it MUST always return false. This information is part of XML infoset:
     *如果解析器非验证它必须始终返回false。这个信息是XML infoset的一部分:;
     * @param index zero-based index of attribute
     * @return false if attribute was in input
     */
    boolean isAttributeDefault(int index);

    /**
     * Returns the given attributes value.
     * 返回给定的属性值
     * Throws an IndexOutOfBoundsException if the index is out of range
     * or current event type is not START_TAG.
     *
     * <p><strong>NOTE:</strong> attribute value must be normalized
     * 属性值必须规范化
     * (including entity replacement text if PROCESS_DOCDECL is false) as described in
     * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section
     * 3.3.3 Attribute-Value Normalization</a>
     *
     * @see #defineEntityReplacementText
     *
     * @param index zero-based index of attribute
     * @return value of attribute (null is never returned)
     */
    String getAttributeValue(int index);

    /**
     * Returns the attributes value identified by namespace URI and namespace localName.
     * 返回属性值由命名空间URI和名称空间标识本地名称
     * If namespaces are disabled namespace must be null.
     * 如果名称空间被禁用名称空间必须为空
     * If current event type is not START_TAG then IndexOutOfBoundsException will be thrown.
     *如果当前的事件类型不是开始标记然后索引越界就会抛出异常。
     * <p><strong>NOTE:</strong> attribute value must be normalized
     * (including entity replacement text if PROCESS_DOCDECL is false) as described in
     * <a href="http://www.w3.org/TR/REC-xml#AVNormalize">XML 1.0 section
     * 3.3.3 Attribute-Value Normalization</a>
     *
     * @see #defineEntityReplacementText
     *
     * @param namespace Namespace of the attribute if namespaces are enabled otherwise must be null
     * @param name If namespaces enabled local name of attribute otherwise just attribute name
     * @return value of attribute or null if attribute with given name does not exist
     */
    String getAttributeValue(String namespace,
                                    String name);

    // --------------------------------------------------------------------------
    // actual parsing methods
    //实际的解析方法;

    /**
     * Returns the type of the current event (START_TAG, END_TAG, TEXT, etc.)
     *
     * @see #next()
     * @see #nextToken()
     */
    int getEventType()
        throws XmlPullParserException;

    /**
     * Get next parsing event - element content will be coalesced and only one TEXT event must be returned for whole element content
     * 得到下一个解析事件——元素内容将合并和只有一个文本事件必须返回整个元素内容
     * (comments and processing instructions will be ignored and entity references must be expanded or exception mus be thrown if entity reference can not be expanded).
     * 注释和处理指令将被忽略和实体引用必须扩大或异常亩被如果不能扩大实体引用)。
     * If element content is empty (content is "") then no TEXT event will be reported.
     *如果元素的内容是空的(内容”),那么没有文本事件报道。
     * <p><b>NOTE:</b>
     * empty element (such as &lt;tag/>) will be reported with  two separate events: START_TAG, END_TAG - it must be so to preserve parsing equivalency of empty element to &lt;tag>&lt;/tag>.
     * 空元素(如& lt;标签/ >)将与两个独立的事件:报道开始标记、结束标记,它必须保存解析相等的空元素& lt;标签> & lt;/ >标签
     *  (see isEmptyElementTag ())
     *
     * @see #isEmptyElementTag
     * @see #START_TAG
     * @see #TEXT
     * @see #END_TAG
     * @see #END_DOCUMENT
     */

    int next()
        throws XmlPullParserException, IOException;


    /**
     * This method works similarly to next() but will expose additional event types
     * 这种方法类似于next(),但将使额外的事件类型
     * (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or
     * IGNORABLE_WHITESPACE) if they are available in input.
     *
     * <p>If special feature
     * 如果特殊特性
     * <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">FEATURE_XML_ROUNDTRIP</a>
     * (identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip)
     * is enabled it is possible to do XML document round trip ie. reproduce exectly on output the XML input using getText():
     * 启用XML文档可以做往返ie。恰在繁殖输出的XML输入文本使用get():;
     * returned content is always unnormalized (exactly as in input).
     * 返回的内容总是非规范(在输入完全一样)。
     * Otherwise returned content is end-of-line normalized as described
     * 否则返回内容是行尾的规范化描述;
     * <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a>
     * and.
     * Also when this feature is enabled exact content of
     * 当启用该特性的内容
     * START_TAG, END_TAG,
     * DOCDECL and PROCESSING_INSTRUCTION is available.
     *
     * <p>Here is the list of tokens that can be  returned from
     * nextToken() and what getText() and getTextCharacters() returns:<dl>
     * <dt>START_DOCUMENT<dd>null
     * <dt>END_DOCUMENT<dd>null
     * <dt>START_TAG<dd>null unless FEATURE_XML_ROUNDTRIP
     *   enabled and then returns XML tag, ex: &lt;tag attr='val'>
     * <dt>END_TAG<dd>null unless FEATURE_XML_ROUNDTRIP
     *  id enabled and then returns XML tag, ex: &lt;/tag>
     * <dt>TEXT<dd>return element content.
     *  <br>Note:
     *  that element content may be delivered in multiple consecutive TEXT events.
     *  元素的内容可能会在多个连续文本事件。
     * <dt>IGNORABLE_WHITESPACE<dd>return characters that are determined to be ignorable white space.
     * 返回字符被确定为可忽略的白色空间。
     * If the FEATURE_XML_ROUNDTRIP is enabled all whitespace content outside root element will always reported as IGNORABLE_WHITESPACE otherwise reporting is optional.
     * 如果该功能启用XML往返根元素之外的所有空白内容总是报告为可忽略的空格,否则报告是可选的。
     *  <br>Note:
     *  that element content may be delivered in multiple consecutive IGNORABLE_WHITESPACE events.
     *  元素内容可能会在多个连续可忽略空白的事件。
     * <dt>CDSECT<dd>
     * return text <em>inside</em> CDATA
     *  (ex. 'fo&lt;o' from &lt;!CDATA[fo&lt;o]]>)
     * <dt>PROCESSING_INSTRUCTION<dd>
     *  if FEATURE_XML_ROUNDTRIP is true
     *  return exact PI content ex: 'pi foo' from &lt;?pi foo?>
     *  otherwise it may be exact PI content or concatenation of PI target,
     *  否则它可能确切ππ目标的内容或连接,
     * space and data so for example for
     *   &lt;?target    data?> string &quot;target data&quot; may
     *       be returned if FEATURE_XML_ROUNDTRIP is false.
     * <dt>COMMENT<dd>return comment content ex. 'foo bar' from &lt;!--foo bar-->
     * <dt>ENTITY_REF<dd>getText() MUST return entity replacement text if PROCESS_DOCDECL is false
     * otherwise getText() MAY return null,
     * additionally getTextCharacters() MUST return entity name
     * (for example 'entity_name' for &amp;entity_name;).
     * <br><b>NOTE:</b> this is the only place where value returned from getText() and
     *   getTextCharacters() <b>are different</b>
     * <br><b>NOTE:</b> it is user responsibility to resolve entity reference
     *    if PROCESS_DOCDECL is false and there is no entity replacement text set in
     *    defineEntityReplacementText() method (getText() will be null)
     * <br><b>NOTE:</b> character entities (ex. &amp;#32;) and standard entities such as
     *  &amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos; are reported as well
     *  and are <b>not</b> reported as TEXT tokens but as ENTITY_REF tokens!
     *  This requirement is added to allow to do roundtrip of XML documents!
     * <dt>DOCDECL<dd>
     * if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false
     * then return what is inside of DOCDECL for example it returns:<pre>
     * &quot; titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
     * [&lt;!ENTITY % active.links "INCLUDE">]&quot;</pre>
     * <p>for input document that contained:<pre>
     * &lt;!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
     * [&lt;!ENTITY % active.links "INCLUDE">]></pre>
     * otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true
     *    then what is returned is undefined (it may be even null)
     * </dd>
     * </dl>
     *
     * <p><strong>NOTE:</strong> there is no guarantee that there will only one TEXT or
     * IGNORABLE_WHITESPACE event from nextToken() as parser may chose to deliver element content in
     * multiple tokens (dividing element content into chunks)
     *
     * <p><strong>NOTE:</strong> whether returned text of token is end-of-line normalized
     *  is depending on FEATURE_XML_ROUNDTRIP.
     *
     * <p><strong>NOTE:</strong> XMLDecl (&lt;?xml ...?&gt;) is not reported but its content
     * is available through optional properties (see class description above).
     *
     * @see #next
     * @see #START_TAG
     * @see #TEXT
     * @see #END_TAG
     * @see #END_DOCUMENT
     * @see #COMMENT
     * @see #DOCDECL
     * @see #PROCESSING_INSTRUCTION
     * @see #ENTITY_REF
     * @see #IGNORABLE_WHITESPACE
     */
    int nextToken()
        throws XmlPullParserException, IOException;

    //-----------------------------------------------------------------------------
    // utility methods to mak XML parsing easier ...
    //实用程序方法mak XML解析容易……;

    /**
     * Test if the current event is of the given type and if the
     * namespace and name do match. null will match any namespace
     * and any name. If the test is not passed, an exception is
     * thrown. The exception text indicates the parser position,
     * the expected event and the current event that is not meeting the
     * requirement.
     *
     * <p>Essentially it does this
     * <pre>
     *  if (type != getEventType()
     *  || (namespace != null &amp;&amp;  !namespace.equals( getNamespace () ) )
     *  || (name != null &amp;&amp;  !name.equals( getName() ) ) )
     *     throw new XmlPullParserException( "expected "+ TYPES[ type ]+getPositionDescription());
     * </pre>
     */
    void require(int type, String namespace, String name)
        throws XmlPullParserException, IOException;

    /**
     * If current event is START_TAG then if next element is TEXT then element content is returned or if next event is END_TAG then empty string is returned,
     * 如果当前的事件开始标记然后如果下一个元素的文本元素内容或者返回下一个事件是结束标记然后返回空字符串,
     * otherwise exception is thrown.
     * 否则异常
     * After calling this function successfully parser will be positioned on END_TAG.
     *成功后调用此函数解析器将在结束标记定位
     * <p>The motivation for this function is to allow to parse consistently both empty elements and elements that has non empty content, for example for input:
     * 这个函数是允许他动机来解析一直空元素和元素,非空的内容,例如输入:;
     * <ol>
     * <li>&lt;tag&gt;foo&lt;/tag&gt;
     * <li>&lt;tag&gt;&lt;/tag&gt; (which is equivalent to &lt;tag/&gt;
     * both input can be parsed with the same code:
     * <pre>
     *   p.nextTag()
     *   p.requireEvent(p.START_TAG, "", "tag");
     *   String content = p.nextText();
     *   p.requireEvent(p.END_TAG, "", "tag");
     * </pre>
     * This function together with nextTag make it very easy to parse XML that has
     * no mixed content.
     *
     *
     * <p>Essentially it does this
     * <pre>
     *  if(getEventType() != START_TAG) {
     *     throw new XmlPullParserException(
     *       "parser must be on START_TAG to read next text", this, null);
     *  }
     *  int eventType = next();
     *  if(eventType == TEXT) {
     *     String result = getText();
     *     eventType = next();
     *     if(eventType != END_TAG) {
     *       throw new XmlPullParserException(
     *          "event TEXT it must be immediately followed by END_TAG", this, null);
     *      }
     *      return result;
     *  } else if(eventType == END_TAG) {
     *     return "";
     *  } else {
     *     throw new XmlPullParserException(
     *       "parser must be on START_TAG or TEXT to read text", this, null);
     *  }
     * </pre>
     *
     * <p><strong>Warning:</strong>
     * Prior to API level 14, the pull parser returned by
     * 在API级别14之前,pull解析器返回的;{@code
     * android.util.Xml}
     * did not always advance to the END_TAG event when this method was called.
     * 并不总是提前结束标记事件时,这种方法被称为
     * Work around by using manually advancing after calls to nextText():
     * 工作通过使用手动推进后调用下一个文本()<pre>
     *  String text = xpp.nextText();
     *  if (xpp.getEventType() != XmlPullParser.END_TAG) {
     *      xpp.next();
     *  }
     * </pre>
     */
    String nextText() throws XmlPullParserException, IOException;

    /**
     * Call next() and return event if it is START_TAG or END_TAG otherwise throw an exception.
     * 下一个()的调用和返回事件如果是开始标签和结束标签,否则抛出异常。
     * It will skip whitespace TEXT before actual tag if any.
     *它会跳过空格文本之前实际标签
     * <p>essentially it does this
     * 本质上它;
     * <pre>
     *   int eventType = next();
     *   if(eventType == TEXT &amp;&amp;  isWhitespace()) {   // skip whitespace
     *      eventType = next();
     *   }
     *   if (eventType != START_TAG &amp;&amp;  eventType != END_TAG) {
     *      throw new XmlPullParserException("expected start or end tag", this, null);
     *   }
     *   return eventType;
     * </pre>
     */
    int nextTag() throws XmlPullParserException, IOException;

}
